Summary

• harden administration upsert payload handling to normalize org IDs, sanitize nested undefined fields, and validate required assessment fields before write
• harden assignment fan-out write paths to sanitize assignment payloads immediately before transaction writes
• add dedicated documentation of the disappearing-assignment issue, root cause categories, and mitigation strategy in functions/levante-admin/README_DISAPPEARING_ASSIGNMENTS.md

Issue context

Users reported that assignment creation could appear successful while one or more users were missing assignment docs. Investigation showed two categories:

1. expected non-assignment due to assignment conditions (e.g., userType == student)
2. true backend risk where malformed/undefined payload fields can break async fan-out writes

This PR addresses category (2) directly by preventing malformed data from reaching Firestore write paths.

What changed

functions/levante-admin/src/upsertAdministration.ts

• normalize and dedupe org ID lists
• recursively remove undefined fields from assessments/legal payloads
• normalize assessment.params to object shape
• validate required assessment keys (taskId, variantId, variantName)
• reject invalid dates explicitly
• preserve/guarantee non-empty createdBy on updates

functions/levante-admin/src/assignments/assignment-utils.ts

• use cleaned assessments when building assignment docs
• sanitize assignment payloads before transaction.set(...) in add/update fan-out paths

functions/levante-admin/src/utils/utils.ts

• update removeUndefinedFields() to recursively clean nested arrays (not only top-level undefined entries)

Documentation

• added functions/levante-admin/README_DISAPPEARING_ASSIGNMENTS.md with:
  • issue summary
  • root-cause split (expected non-assignment vs real fan-out failure)
  • fix rationale
  • operational recommendations

Why this should fix the issue

Assignment fan-out (updateAssignmentsForOrgChunk) is asynchronous and can fail on malformed write payloads. This patch sanitizes and validates data both at ingress (upsertAdministration) and immediately before assignment writes, reducing partial/failed propagation caused by undefined and malformed fields.

Test plan

• verified lint diagnostics for touched files (no IDE lint issues on changed files)
• reproduced and analyzed assignment behavior against live environment
• run full workspace TS build in CI environment with all workspace deps installed
• run emulator integration pass focused on administration upsert + assignment fan-out

Related support-side change

levante-support bug-806 test update was pushed directly to main to align test expectations with assignment conditions and keep assignment audit artifacts.

Made with Cursor